ValueScan 开放 API 文档

简体中文

English
繁體中文
Tiếng Việt

简体中文

English
繁體中文
Tiếng Việt

Appearance

新大盘分析SSE订阅 ​

连接地址：https://stream.valuescan.ai/stream/market/analysis/subscribe

一、概述 ​

大盘分析是 ValueAgent 通过多维度数据，对 BTC/ETH/SOL 的行情进行综合分析的输出结果。本接口为新枚举版 SSE 订阅，每 5 分钟生成新的分析结果后进行推送。signal 使用国际通用交易术语（LONG / SHORT / SIDEWAYS），并附带日内信号分布汇总（h24Summary）与信号验证结果（verdict）。

与旧版 /stream/market/subscribe 的区别：

对比项原有大盘分析订阅新大盘分析 SSE 订阅（本接口）
订阅地址/stream/market/subscribe/stream/market/analysis/subscribe
事件名marketmarket-analysis
content大盘分析纯文本需二次解析的结构化 JSON 字符串
signal不单独返回LONG / SHORT / SIDEWAYS
扩展字段无结构化扩展字段返回 h24Summary、verdict、verdictDesc 等字段
更新方式行情变化时推送每 5 分钟生成新分析结果后推送

signal 表示当前 5 分钟分析周期得出的方向。每个周期都直接返回 LONG、SHORT 或 SIDEWAYS；若方向与上一周期相同，仍返回相同的基础枚举值，不使用 LONG_CONTINUE、SHORT_CONTINUE 或 SIDEWAYS_CONTINUE。

二、订阅地址 ​

GET https://stream.valuescan.ai/stream/market/analysis/subscribe

鉴权参数（Query String）：

参数类型必需说明
apiKeystring是ValueScan Access Key
signstring是HMAC-SHA256 签名
timestamplong是毫秒级 Unix 时间戳
noncestring是随机字符串（防重放）

签名算法：

sign = HMAC-SHA256(SK, timestamp毫秒 + nonce)

点数消耗 ​

  • 消耗点数：每 30 分钟 50 点数

三、SSE 事件格式 ​

连接成功 ​

event: connected
data: subscribed

心跳（维持连接） ​

: heartbeat

event: heartbeat
data: ping

服务端每 20 秒发送一次心跳。

大盘分析推送 ​

event: market-analysis
data: {"ts":1775604300144,"uniqueId":"大盘分析_20260408103000","content":"{\"vsTokenId\":\"1\",\"symbol\":\"BTC\",\"signal\":\"SIDEWAYS\",\"price\":\"80573.75\",\"klineDiff\":\"-0.00298373\",\"supports\":[\"80434.275\",\"79980.475\"],\"resistances\":[\"80776.78\",\"81208.86\"],\"analysis\":\"📊 BTC 日内主力资金趋势分析(ValueScan)...\",\"analysisTime\":1778837430000,\"verdict\":0,\"verdictDesc\":\"待验证\",\"h24Summary\":{\"buyCount\":12,\"sellCount\":5,\"holdCount\":7,\"total\":24,\"buyRatio\":50.0,\"sellRatio\":20.8,\"holdRatio\":29.2,\"conclusion\":\"LONG_BIASED_SIDEWAYS\"}}"}

market-analysis 事件 payload 字段：

字段类型说明
tslong推送时间（毫秒时间戳）
uniqueIdstring唯一标识（用于去重）
contentstring大盘分析详情 JSON 字符串，需二次解析

content 解析后的字段结构：

字段类型说明
vsTokenIdstring代币 ID
symbolstring代币符号（如 BTC、ETH）
iconstring代币图标 URL
pricestring分析时价格
signalstring当前 5 分钟分析周期的 AI 综合信号：LONG（利多）/ SHORT（利空）/ SIDEWAYS（震荡）
klineDiffstringK 线涨跌幅（小数）
supportsarray<string>支撑位价格列表
resistancesarray<string>压力位价格列表
analysisstringAI 分析结论（请求语言版本）
analysisTimelong分析时间（毫秒时间戳）
verdictinteger信号验证结果：0=待验证，1=相符，2=不符合
verdictDescstring信号验证结果描述
h24Summaryobject日内信号分布汇总
h24Summary.buyCountinteger利多次数
h24Summary.sellCountinteger利空次数
h24Summary.holdCountinteger震荡次数
h24Summary.totalinteger总计次数
h24Summary.buyRationumber利多占比（%）
h24Summary.sellRationumber利空占比（%）
h24Summary.holdRationumber震荡占比（%）
h24Summary.conclusionstring日内综合结论：LONG（利多行情）/ SHORT（利空行情）/ SIDEWAYS（震荡）/ LONG_BIASED_SIDEWAYS（震荡偏多）/ SHORT_BIASED_SIDEWAYS（震荡偏空）

四、新旧枚举对照 ​

旧值（旧 SSE）新值（本接口）含义
BUYLONG利多
SELLSHORT利空
HOLDSIDEWAYS震荡
BULLISHLONG利多行情
BEARISHSHORT利空行情
OSCILLATESIDEWAYS震荡
OSCILLATE_BULLISHLONG_BIASED_SIDEWAYS震荡偏多
OSCILLATE_BEARISHSHORT_BIASED_SIDEWAYS震荡偏空

五、订阅示例 ​

Python ​

python
import hashlib
import hmac
import json
import time
import uuid
import urllib.request
from urllib.parse import urlencode

AK = "your-access-key"
SK = "your-secret-key"

ts = int(time.time() * 1000)
nonce = uuid.uuid4().hex
sign = hmac.new(
    SK.encode(),
    (str(ts) + nonce).encode(),
    hashlib.sha256,
).hexdigest()

params = urlencode({
    "apiKey": AK,
    "sign": sign,
    "timestamp": ts,
    "nonce": nonce,
})

url = f"https://stream.valuescan.ai/stream/market/analysis/subscribe?{params}"
req = urllib.request.Request(url, headers={"Accept": "text/event-stream"})

with urllib.request.urlopen(req, timeout=300) as resp:
    event_name = ""
    data_str = ""
    for raw in resp:
        line = raw.decode("utf-8").rstrip("\r\n")

        if line.startswith(":"):
            print("♥ 心跳")
            continue

        if line == "":
            if data_str:
                handle_event(event_name, data_str)
            event_name = ""
            data_str = ""
        elif line.startswith("event:"):
            event_name = line[6:].strip()
        elif line.startswith("data:"):
            data_str = line[5:].strip()


def handle_event(event_name: str, data_str: str) -> None:
    if event_name == "connected":
        print(f"[连接] {data_str}")
    elif event_name == "market-analysis":
        payload = json.loads(data_str)
        content = json.loads(payload["content"])
        print(f"[大盘分析] {content['symbol']} signal={content['signal']} "
              f"price={content['price']} conclusion={content['h24Summary']['conclusion']}")

cURL（快速验证） ​

bash
python3 -c "
import hashlib, hmac, time, uuid, urllib.parse
SK='your-secret-key'
ts=int(time.time()*1000)
nonce=uuid.uuid4().hex
sign=hmac.new(SK.encode(), (str(ts)+nonce).encode(), hashlib.sha256).hexdigest()
params=urllib.parse.urlencode({'apiKey':'your-access-key','sign':sign,'timestamp':ts,'nonce':nonce})
print(f\"curl -N 'https://stream.valuescan.ai/stream/market/analysis/subscribe?{params}' -H 'Accept: text/event-stream'\")
'"

六、断线重连 ​

与旧版大盘订阅一致，建议实现指数退避重连：

python
def listen_with_retry(url: str, max_retries: int = 10) -> None:
    retries = 0
    while retries <= max_retries:
        try:
            req = urllib.request.Request(url, headers={"Accept": "text/event-stream"})
            with urllib.request.urlopen(req, timeout=300) as resp:
                _read_sse(resp)
                break
        except KeyboardInterrupt:
            print("用户中断，退出。")
            break
        except Exception as e:
            retries += 1
            wait = min(2 ** retries, 60)
            print(f"连接断开（{e}），{wait}s 后第 {retries} 次重连...")
            time.sleep(wait)
    else:
        print("重试次数耗尽，退出。")

七、错误码 ​

建连阶段的鉴权、参数、额度类业务错误会以 HTTP 200 返回业务 JSON，响应体中的 code 表示实际错误原因。

示例：

json
{
    "code": 20021,
    "message": "Signature verification failed",
    "data": null,
    "requestId": "a7d7ce3053e140dca91d93df173648f8"
}

常见错误码：

code说明
20001API Key 缺失
20002API Key 无效、已禁用、已过期或未审核通过
20010时间戳缺失
20011时间戳格式错误
20012时间戳过期
20020签名缺失
20021签名验证失败
40001必填参数缺失
40002参数格式或取值不合法
60001触发限流
70001OpenApi 点数不足

连接建立后，如果点数不足，会收到 credit-exhausted 事件，随后连接关闭：

event: credit-exhausted
data: {"message":"额度已耗尽，请充值"}